接口标准文档

1. 文档信息

文档名称：SERVICEME系统接口标准文档
版本号：v1.0
发布日期：2025-07-18
适用范围：适用于企业智能化场景，支持身份认证、知识问答、流程自动化、数据分析与内容生成等功能。接口采用标准 RESTful 架构，便于系统集成与跨平台应用，广泛用于客服、营销、财务、人力资源等业务模块，提升协同效率与智能决策能力。

2. 修订记录

版本号	修订日期	修订内容
v1.0	2025-07-18	初稿

3. 概述

3.1 文档目的

说明文档的目标，例如：

本文档定义了SERVICEME系统的接口规范，包括请求格式、响应格式、错误码等，供调用方参考。

3.2 术语与缩写

API：应用程序接口
HTTP：超文本传输协议
JSON：JavaScript对象表示法
RESTful：一种API设计风格

3.3 接口设计原则

遵循RESTful风格（如适用）。
使用HTTPS协议保证安全性。
数据格式统一为JSON。
接口版本化管理（如/v1/xxx）。

4. 通用规范

4.1 请求规范

请求方法：GET/POST/PUT/DELETE等。
请求头（Headers）：
- Content-Type: application/json
- Authorization: Bearer {token}（如需要认证）。
请求参数：
- Query参数（GET）、Body参数（POST/PUT）。
- 必填/可选字段说明。

4.2 响应规范

响应格式：

{
  "code": 200,       // 状态码
  "message": "成功",  // 描述信息
  "data": {}         // 返回数据（可选）
}

HTTP状态码：
- 200：成功
- 400：请求参数错误
- 401：未授权
- 500：服务器内部错误

4.3 错误码表

错误码	含义	解决方案建议
200	成功	-
422	参数错误	-
40001	参数缺失	检查必填字段
50001	服务器内部错误	联系管理员

5. 接口详情

5.1 接口1：获取用户信息

接口路径：GET /lite_api/v1/iam/user/{user_id}
请求参数：

参数名类型必填说明
userId Path 是用户ID

参数名	类型	必填	说明
userId	Path	是	用户ID

请求示例：

GET /v1/iam/user/293456 HTTP/1.1
Authorization: Bearer abcdef123456

响应示例：

{
    "code": 200,
    "data": {
        "username": "string",
        "email": "string",
        "real_name": "",
        "nickname": "",
        "is_superuser": false,
        "avatar": "",
        "enable": true,
        "id": "string",
        "is_aad": false,
        "serial_number": "string",
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z",
        "last_login": "2019-08-24T14:15:22.123Z",
        "roles": [],
        "user_roles": [],
        "organizations": [],
        "gender": 0,
        "birthday": "2019-08-24T14:15:22.123Z",
        "wechat": "string",
        "region": "string",
        "time_difference": 0,
        "join_time": "2019-08-24T14:15:22.123Z",
        "office_phone": "string",
        "mobile_phone": "string",
        "description": "string"
    },
    "message": "success"
}

5.2 接口2：创建用户

接口路径：POST /lite_api/v1/iam/user/
请求参数：

参数名类型必须说明
username string 是用户名
email string 是邮箱
real_name string 是真实姓名

参数名	类型	必须	说明
username	string	是	用户名
email	string	是	邮箱
real_name	string	是	真实姓名

请求示例：

{
    "username": "string",
    "email": "",
    "real_name": "",
}

响应示例：

{
    "username": "string",
    "email": "string",
    "real_name": "",
}

5.3 接口3：创建助手

接口路径：POST /lite_api/v1/robots/

请求参数：

参数名	类型	必须	说明
info	object	是	助手信息及名称
masks	array	否	助手面具
knowledge_bases	array	否	知识库
skills	array	否	技能
mcps	array	否	数据模型
data_sources	array	否	数据源
keywords_filter	object	否	关键词过滤
feedback_accounts	array	否	反馈帐号

请求示例：

{
    "info": {
        "name": "string",
        "weight": 0,
        "avatar_url": "string",
        "description": "",
        "prompt": "string",
        "prologue": "string",
        "robot_type": "",
        "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
        "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
        "product_position": "chat-x",
        "chat_rounds": 0,
        "user_id": "string",
        "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
        "split_type": "string",
        "load_type": "string",
        "spliter_json": "string",
        "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
        "user_skill_auths": [
            null
        ],
        "need_summary": true,
        "force_execute": true,
        "open_filter": true,
        "record_chat": true,
        "is_published": true,
        "category_ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ],
        "recommend_question": false,
        "feedback": false,
        "knowledge_config": {
            "search_mode": "hybrid",
            "k": 5,
            "doc_score": 0.7,
            "qa_score": 0.8,
            "metadata": "none",
            "show_reference": false
        },
        "editable": true,
        "question_guide": false,
        "operator_execute": false,
        "bi_config": {
            "query_rewrite": false,
            "divide_think": false
        }
    },
    "masks": [
        {
            "mask_set_id": "d0bee2ed-0859-4bb6-8598-f64d47a5a28b"
        }
    ],
    "knowledge_bases": [
        {
            "classification_id": "string",
            "classification_name": "string",
            "classification_icon": "string",
            "workspaces": []
        }
    ],
    "skills": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "mcps": [],
    "data_sources": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "keywords_filter": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
        "key_words": [
            "string"
        ],
        "review_input": true,
        "preset_reply_input": "string",
        "review_output": true,
        "preset_reply_output": "string"
    },
    "feedback_accounts": []
}

响应示例

{
    "code": 200,
    "data": null,
    "message": "success"
}

5.4 接口4：获取助手

接口路径：POST /lite_api/v1/robots/{robot_id}
请求参数：

参数名	类型	必须	说明
robot_id	string	是	助手ID
internal_use	boolean	否	是否内部使用

请求示例：

GET /lite_api/v1/robots/00001 HTTP/1.1
Authorization: Bearer abcdef123456

响应示例：

{
    "code": 200,
    "data": {
        "info": {
            "name": "string",
            "weight": 0,
            "avatar_url": "string",
            "description": "",
            "prompt": "string",
            "prologue": "string",
            "robot_type": "",
            "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
            "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
            "product_position": "chat-x",
            "chat_rounds": 0,
            "user_id": "string",
            "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
            "split_type": "string",
            "load_type": "string",
            "spliter_json": "string",
            "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
            "user_skill_auths": [
                null
            ],
            "need_summary": true,
            "force_execute": true,
            "open_filter": true,
            "record_chat": true,
            "is_published": true,
            "category_ids": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ],
            "recommend_question": false,
            "feedback": false,
            "knowledge_config": {
                "search_mode": "hybrid",
                "k": 5,
                "doc_score": 0.7,
                "qa_score": 0.8,
                "metadata": "none",
                "show_reference": false
            },
            "editable": true,
            "question_guide": false,
            "operator_execute": false,
            "bi_config": {
                "query_rewrite": false,
                "divide_think": false
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "manageable": false
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
            "key_words": [
                "string"
            ],
            "review_input": true,
            "preset_reply_input": "string",
            "review_output": true,
            "preset_reply_output": "string"
        },
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 接口5：上传文件

接口路径：POST /Api/Workspace/File/UploadFiles
请求参数：

参数名	类型	必须	说明
Files	array	否	本次上传的文件
WorkspaceId	string	否	string
FullPath	string	否	文件要上传到的完整路径
IsCover	boolean	否	是否系统上传
UserId	integer	否	用户id (用于公开api)
UserEmail	string	否	用户邮箱(用于公开api)
OCRMode	string	否	OCR模式

响应示例：

{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

6. 安全规范

认证方式：OAuth2.0/JWT/API Key。
数据加密：敏感字段需加密传输（如密码）。

限流策略：接口调用频率限制参考下表。

场景	常见限制	说明
开放API（如第三方调用）	10~100 次/分钟	例如微信支付、支付宝开放API通常限制50~200次/分钟（具体看接口等级）。
内部系统API	100~1000 次/分钟	内部服务间调用可放宽，但需避免单服务过度占用资源。
用户行为接口	5~60 次/分钟	例如登录、短信发送等敏感操作，需严格限制（如短信验证码接口通常限制1次/60秒）。
数据查询接口	100~5000 次/分钟	高频查询接口可适当放宽，但需配合缓存降低数据库压力。
高并发核心接口	动态限流（如令牌桶算法）	例如电商秒杀接口，可能结合熔断机制和弹性伸缩。

1. 文档信息​

2. 修订记录​

3. 概述​

3.1 文档目的​

3.2 术语与缩写​

3.3 接口设计原则​

4. 通用规范​

4.1 请求规范​

4.2 响应规范​

4.3 错误码表​

5. 接口详情​

5.1 接口1：获取用户信息​

5.2 接口2：创建用户​

5.3 接口3：创建助手​

5.4 接口4：获取助手​

5.5 接口5：上传文件​

6. 安全规范​

1. 文档信息

2. 修订记录

3. 概述

3.1 文档目的

3.2 术语与缩写

3.3 接口设计原则

4. 通用规范

4.1 请求规范

4.2 响应规范

4.3 错误码表

5. 接口详情

5.1 接口1：获取用户信息

5.2 接口2：创建用户

5.3 接口3：创建助手

5.4 接口4：获取助手

5.5 接口5：上传文件

6. 安全规范